home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / FROMUTS / DDEPASCAL / DDE / !PC / h / dbox < prev    next >
Text File  |  1992-02-10  |  18KB  |  441 lines
  1. (*
  2.  * Title: h.dbox
  3.  * Purpose: Creation/deletion/manipulation of dialogue boxes.
  4.  *
  5.  *)
  6.  
  7. (* 
  8.  * It is important to note that the structure of your dialogue templates is
  9.  * an integral part of your program. Always use symbolic names for templates
  10.  * and for fields and action buttons within them.  Templates for the
  11.  * dialogue boxes can be loaded using the template module in this library
  12.  *
  13.  *)
  14.  
  15. (* 
  16.  * See separate documentation for how to use the RISC OS Template Editor
  17.  * in conjunction with this interface. 
  18.  *)
  19.  
  20. #ifndef __dbox_h
  21. #define __dbox_h
  22.  
  23.  
  24. (* ------------------------------ dbox ------------------------------------
  25.  * a dbox is an abstract dialogue box handle
  26.  *
  27.  *)
  28. type dbox = ^dbox__str;
  29.      dbox__str = record end;
  30.  
  31.  
  32.  
  33. (* ********************** Creation, Deletion functions ***************** *)
  34.  
  35.  
  36. (* ------------------------------ dbox_new ------------------------------
  37.  * Description:   Builds a dialogue box from a named template 
  38.  *                Template editor (FormEd) may have been used to create
  39.  *                this template in the "Templates" file for the application.
  40.  *
  41.  * Parameters:    char *name -- template name (from templates previously
  42.  *                              read in by template_init), from which to
  43.  *                              construct dialogue box. Name is as given
  44.  *                              when using FormEd to create template
  45.  * Returns:       On successful completion, pointer to a dialogue box
  46.  *                structure otherwise null (eg. when not enough space).
  47.  * Other Info:    This only creates a structure. It doesn't display anything!
  48.  *                *However* it does register the dialogue box as an active 
  49.  *                window with the window manager.
  50.  *)
  51. function dbox_new(name : string) : dbox; extern;
  52.  
  53.  
  54. (* ------------------------------ dbox_dispose ----------------------------
  55.  * Description:   Disposes of dialogue box structure.
  56.  *
  57.  * Parameters:    dbox* -- pointer to pointer to a dialogue box structure
  58.  * Returns:       void.
  59.  * Other Info:    This also has the side-efffect of hiding the dialogue box,
  60.  *                so that it no longer appears on the screen. It also
  61.  *                "un-registers" it as an active window with the
  62.  *                window manager.
  63.  *)
  64. procedure dbox_dispose(var d : dbox); extern;
  65.  
  66.  
  67.  
  68. (* *************************** Display functions ************************ *)
  69.  
  70. (* ----------------------------- dbox_show --------------------------------
  71.  * Description:   Displays given dialogue box on the screen.
  72.  *
  73.  * Parameters:    dbox -- dialogue box to be displayed
  74.  *                        (typically created by dbox_new)
  75.  * Returns:       void.
  76.  * Other Info:    Typically used when dialogue box is from a submenu
  77.  *                so that it disappears when the menu is closed. If called
  78.  *                when dialogue box is showing then no effect. The show will
  79.  *                occur near the last menu selection or last caret setting
  80.  *                (whichever is most recent).
  81.  *)  
  82. procedure dbox_show(d : dbox); extern;
  83.  
  84.  
  85. (* ----------------------------dbox_showstatic ----------------------------
  86.  * Description:   Displays given dialogue box on the screen, and leaves it
  87.  *                there, until explicitly closed.
  88.  *
  89.  * Parameters:    dbox -- dialogue box to be displayed
  90.  *                        (typically created by dbox_new)
  91.  * Returns:       void.
  92.  * Other Info:    typically, not used from menu selection, because it will
  93.  *                persist longer than the menu (otherwise same as dbox_show).
  94.  *)
  95. procedure dbox_showstatic(d : dbox); extern;
  96.  
  97.  
  98. (* ----------------------------- dbox_hide --------------------------------
  99.  * Description:   Hides a previously displayed dialogue box.
  100.  * 
  101.  * Parameters:    dbox -- dialogue box to be hidden
  102.  * Returns:       void.
  103.  * Other Info:    Note that this does not release any storage. It just
  104.  *                hides the dialogue box. If called when dialogue box  is
  105.  *                already hidden, then no effect.
  106.  *)
  107. procedure dbox_hide(d : dbox); extern;
  108.  
  109.  
  110.  
  111.  
  112. (* ***************************** dbox Fields. *************************** *)
  113.  
  114. (* A dbox has a number of fields, labelled from 0. There are the following
  115.  * distinct field types:
  116.  *
  117.  * "action" fields. Mouse clicks here are communicated to the client. The 
  118.  * fields are usually labelled "go", "quit", etc. Set/GetField apply to the
  119.  * label on the field, although this is usually set up in the template.
  120.  *
  121.  * "output" fields. These display a message to the user, using SetField.
  122.  *  Mouse clicks etc. have no effect.
  123.  *
  124.  *"input" fields. The user can type into these, and simple local editing is
  125.  * provided. Set/GetField can be used on the textual value, or 
  126.  * Set/GetNumeric if the user should type in numeric values.
  127.  *
  128.  * "on/off" fields. The user can click on these to display their on/off 
  129.  * status. They are always "off" when the dbox is first created. The 
  130.  * template editor can set up mutually exclusive sets of these at will. 
  131.  * Set/GetField apply to the label on this field, Set/GetNumeric 
  132.  * set/get 1 (on) and 0 (off) values.
  133.  *
  134.  *)
  135.  
  136. (* ---------------------- dbox_field / dbox_fieldtype --------------------
  137.  * type dbox_field values are field numbers within a dbox
  138.  * type dbox_fieldtype values indicate what sort a field is
  139.  *                          (ie. action, output, input, on/off)
  140.  *
  141.  *)
  142.  
  143. type dbox_field_ptr = ^dbox_field;
  144.      dbox_field = integer;
  145.  
  146. const dbox_FACTION = 0;
  147.       dbox_FOUTPUT = 1;
  148.       dbox_FINPUT  = 2;
  149.       dbox_FONOFF  = 3;
  150.  
  151. type dbox_fieldtype_ptr = ^dbox_fieldtype;
  152.      dbox_fieldtype = integer;
  153.  
  154.  
  155. (* -------------------------- dbox_setfield -------------------------------
  156.  * Description:   Sets the given field, within the given dialogue box, to 
  157.  *                the given text value.
  158.  *
  159.  * Parameters:    dbox -- the chosen dialogue box
  160.  *                dbox_field -- chosen field number
  161.  *                char* -- text to be displayed in field
  162.  * Returns:       void.
  163.  * Other Info:    if applied to non-text field then no effect
  164.  *                if field is an indirected text icon then the text length
  165.  *                is limited by the size value used when setting up the
  166.  *                template in the template editor. Any longer text will be
  167.  *                truncated to this length.
  168.  *                otherwise text is truncated to 12 chars (11 text + 1 null)
  169.  *                if dbox is currently showing, change is immediately 
  170.  *                visible.
  171.  *                
  172.  *)
  173. procedure dbox_setfield(d : dbox; df : dbox_field; text : string); extern;
  174.  
  175.  
  176. (* ---------------------------- dbox_getfield ------------------------------
  177.  * Description:   Puts the current contents of the chosen text field into
  178.  *                buffer, whose size is given as third parameter
  179.  *
  180.  * Parameters:    dbox -- the chosen dialogue box
  181.  *                dbox_field -- the chosen field number
  182.  *                char *buffer -- buffer to be used
  183.  *                int size -- size of buffer
  184.  * Returns:       void.
  185.  * Other Info:    if applied to non-text field then null string put in buffer
  186.  *                if the length of the chosen field (plus null-terminator)
  187.  *                is larger than the buffer, then result will be truncated.
  188.  *)
  189. procedure dbox_getfield(d : dbox;
  190.                 df : dbox_field;
  191.                 buffer : string;
  192.                 size : integer); extern;
  193.  
  194.  
  195. (* ---------------------------- dbox_setnumeric ----------------------------
  196.  * Description:   Sets the given field, in the given dbox, to the given
  197.  *                integer value.
  198.  *
  199.  * Parameters:    dbox -- the chosen dialogue box
  200.  *                dbox_field -- the chosen field number
  201.  *                int -- field's contents will be set to this value
  202.  * Returns:       void.
  203.  * Other Info:    if field is input/output, then the integer value is
  204.  *                converted to a string and displayed in the field
  205.  *                if field is of type "action" or "on/off" then a non-zero
  206.  *                integer value "selects" this field; zero "de-selects".
  207.  * 
  208.  *)
  209. procedure dbox_setnumeric(d : dbox; df : dbox_field; v : integer); extern;
  210.  
  211.  
  212. (* ---------------------------- dbox_getnumeric ----------------------------
  213.  * Description:   Gets the integer value held in the chosen field of the
  214.  *                chosen dbox.
  215.  * 
  216.  * Parameters:    dbox -- the chosen dialogue box
  217.  *                dbox_field -- the chosen field number
  218.  * Returns:       integer value held in chosen field
  219.  * Other Info:    if the field is of type "on/off" then return value of 0
  220.  *                means "off", 1 means "on"
  221.  *                otherwise return value is integer equivalent of field
  222.  *                contents.
  223.  *
  224.  *)
  225. function dbox_getnumeric(d : dbox; df : dbox_field) : integer; extern;
  226.  
  227.  
  228. (* --------------------------- dbox_fadefield ------------------------------
  229.  * Description:   Makes a field unselectable (ie. faded by WIMP).
  230.  *
  231.  * Parameters:    dbox d -- the dialogue box in which field resides
  232.  *                dbox_field f -- the field to be faded.
  233.  * Returns:       void.
  234.  * Other Info:    Fading an already faded field has no effect.
  235.  *
  236.  *)
  237. procedure dbox_fadefield(d : dbox; df : dbox_field); extern;
  238.  
  239.  
  240. (* --------------------------- dbox_unfadefield ----------------------------
  241.  * Description:   Makes a field selectable (ie "unfades" it).
  242.  *
  243.  * Parameters:    dbox d -- the dialogue box in which field resides
  244.  *                dbox_field f -- the field to be unfaded.
  245.  * Returns:       void.
  246.  * Other Info:    Unfading an already selectable field has no effect
  247.  *
  248.  *)
  249. procedure dbox_unfadefield(d : dbox; df : dbox_field); extern;
  250.  
  251.  
  252. (* ************************ Events from dboxes. ************************ *)
  253.  
  254. (* A dbox acts as an input device: a stream of characters comes from it
  255.  * somewhat like a keyboard, and an up-call can be arranged when input is
  256.  * waiting. 
  257.  *)
  258.  
  259. const dbox_CLOSE = dbox_field(-1);
  260.  
  261. (* dboxes may have a "close" button that is separate from their action
  262.  * buttons, usually in the header of the window. If this is pressed then 
  263.  * CLOSE is returned, this should lead to the dbox being invisible. If the
  264.  * dbox represents a particular pending operation then the operation should 
  265.  * be cancelled. 
  266.  *)
  267.  
  268. (* ------------------------------ dbox_get ---------------------------------
  269.  * Description:   Tells caller which action field has been activated in the
  270.  *                chosen dialogue box
  271.  *
  272.  * Parameters:    dbox -- the chosen dialogue box
  273.  * Returns:       field number of activated field
  274.  * Other Info:    This should only be called from an event handler
  275.  *                (since this is the only situation where it makes sense).
  276.  *
  277.  *) 
  278. function dbox_get(d : dbox) : dbox_field; extern;
  279.  
  280.  
  281. (* ------------------------------ dbox_read ---------------------------------
  282.  * Description:   Tells caller which action field has been activated in the
  283.  *                chosen dialogue box. Does not cancel the event.
  284.  *
  285.  * Parameters:    dbox -- the chosen dialogue box
  286.  * Returns:       field number of activated field
  287.  * Other Info:    This should only be called from an event handler
  288.  *                (since this is the only situation where it makes sense).
  289.  *
  290.  *) 
  291. function dbox_read(d : dbox) : dbox_field; extern;
  292.  
  293.  
  294. (* ------------------------ dbox_eventhandler ------------------------------
  295.  * Description:   Register an event handler function for the given dialogue 
  296.  *                box.
  297.  *
  298.  * Parameters:    dbox -- the chosen dialogue box
  299.  *                dbox_handler_proc -- name of handler function
  300.  *                void *handle -- user-defined handle
  301.  * Returns:       void.
  302.  * Other Info:    When a field of the given dialogue box has been activated
  303.  *                the user-supplied handler function is called.
  304.  *                The handler should be defined in the form:
  305.  *                           void foo (dbox d, void *handle)
  306.  *                When called the function "foo" will be passed the relevant
  307.  *                dialogue box, and its user-defined handle. A typical action
  308.  *                in "foo" would be to call dbox_get to determine which
  309.  *                field was activated. If handler==0 then no function is
  310.  *                installed as a handler (and any existing handler is
  311.  *                "un-registered".
  312.  *
  313.  *)
  314. type dbox_handler_proc = ^procedure handler(d : dbox; handle : pointer);
  315.  
  316. procedure dbox_eventhandler(d : dbox;
  317.                 handler : dbox_handler_proc;
  318.                 handle : pointer); extern;
  319.  
  320.  
  321. (* -------------------------- dbox_raweventhandler -------------------------
  322.  * Description:   Register a "raw" event handler for the given dialogue box.
  323.  *
  324.  * Parameters:    dbox -- the given dialogue box
  325.  *                dbox_raw_handler_proc proc -- handler function for event
  326.  *                void *handle -- user-defined handle.
  327.  * Returns:       void.
  328.  * Other Info:    This registers a function which will be passed "unvetted"
  329.  *                window events. Under the window manager in RISC OS, the
  330.  *                event will be a wimp_eventstr* (see Wimp module). The
  331.  *                supplied handler function should return true if it 
  332.  *                processed the event; if it returns false, then the event
  333.  *                will be passed on to any event handler defined using
  334.  *                dbox_eventhandler() as above. The form of the handler's
  335.  *                function header is:
  336.  *                          BOOL func (dbox d, void *event, void *handle).
  337.  *
  338.  *)
  339. type dbox_raw_handler_proc = ^function handler(d : dbox;
  340.                                        event : pointer;
  341.                                        handle : pointer) : boolean;
  342.  
  343.  
  344.  
  345. (* dboxes are often used to fill in the details of a pending operation. In
  346. this case a down-call driven interface to the entire interaction is often
  347. convenient. The following facilties aid this form of use. *)
  348.  
  349.  
  350. (* -------------------------- dbox_fillin -------------------------------
  351.  * Description:   Process events until a field in the given dialogue box
  352.  *                has been activated.
  353.  *
  354.  * Parameters:    dbox d -- the given dialogue box
  355.  * Returns:       field number of activated field.
  356.  * Other Info:    Handling of harmful events, same as dbox_popup (see below).
  357.  *                On each call to dbox_fillin, the caret is set to the end
  358.  *                of the lowest numbered writeable icon
  359.  *)
  360. procedure dbox_fillin(d : dbox) : dbox_field; extern;
  361.  
  362.  
  363. (* -------------------------- dbox_fillin_fixedcaret --------------------
  364.  * Description:   Process events until a field in the given dialogue box
  365.  *                has been activated.
  366.  *
  367.  * Parameters:    dbox d -- the given dialogue box
  368.  * Returns:       field number of activated field.
  369.  * Other Info:    Same as dbox_fillin, except caret is not set to end of lowest
  370.  *                numbered writeable icon
  371.  *)
  372. procedure dbox_fillin_fixedcaret(d : dbox) : dbox_field; extern;
  373.  
  374.  
  375.  
  376. (* ------------------------------ dbox_popup -------------------------------
  377.  * Description:   Build a dialogue box, from a named template, assign message
  378.  *                to field 1, do a dbox_fillin, destroy the dialogue box,
  379.  *                and return the number of the activated field.
  380.  *
  381.  * Parameters:    char *name -- template name for dialogue box
  382.  *                char *message -- message to be displayed in field 1
  383.  * Returns:       field number of activated field
  384.  * Other Info:    "harmful" events are those which could cause the dialogue 
  385.  *                to fail (eg. keystrokes, mouse clicks). These events will 
  386.  *                cause the dialogue box to receive a CLOSE event.
  387.  *
  388.  *)
  389. procedure dbox_popup(name : string; message : string) : dbox_field; extern;
  390.  
  391.  
  392. (* ------------------------------ dbox_persist -----------------------------
  393.  * Description:   When dbox_fillin has returned an action event, this
  394.  *                function returns true if the user wishes the action to
  395.  *                be performed, but the dialogue box to remain.
  396.  *
  397.  * Parameters:    void.
  398.  * Returns:       BOOL -- does user want dbox to remain on screen?
  399.  * Other Info:    Current implementation returns true when user has clicked
  400.  *                Adjust. Caller should continue round fill-in
  401.  *                loop if return value is true (ie. don't destroy dbox).
  402.  *
  403.  *)
  404. function dbox_persist : boolean; extern;
  405.  
  406.  
  407. (* ***************************** System hook. **************************** *)
  408.  
  409. (* --------------------------- dbox_syshandle ------------------------------
  410.  * Description:   Allows the caller to get a handle on the window associated
  411.  *                with the given dialogue box.
  412.  *
  413.  * Parameters:    dbox -- the given dialogue box
  414.  * Returns:       window handle of dialogue box (this is a wimp_w under the
  415.  *                RISC OS window manager).
  416.  * Other Info:    This could be used to hang a menu off a dialogue box, or
  417.  *                to "customise" the dialogue box in some way. Note that
  418.  *                dbox_dispose will also dispose of any such attached menus.
  419.  *     
  420.  *)
  421. function dbox_syshandle(d : dbox) : integer; extern;
  422.  
  423.  
  424. (* ************************** Initialisation **************************** *)
  425.  
  426. (* ---------------------------- dbox_init ----------------------------------
  427.  * Description:   Prepare for use of dialogue boxes from templates
  428.  *
  429.  * Parameters:    void
  430.  * Returns:       void
  431.  * Other Info:    This function must be called ONCE before any dbox functions
  432.  *                are used. You should call template_init() before this
  433.  *                function.
  434.  *
  435.  *)
  436. procedure dbox_init; extern;
  437.  
  438. #endif
  439.  
  440. (* end dbox.h *)
  441.